home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 25 / Cream of the Crop 25.iso / program / xmsbcp11.zip / XMS.DOC < prev    next >
Text File  |  1997-04-13  |  8KB  |  207 lines
  1.  
  2.  
  3.  
  4.  
  5.     XMSBCP
  6.     XMS Interface for Borland C/C++ and Borland Pascal
  7.     Version 1.1
  8.  
  9.     Developed by Tanescu A. Horatiu
  10.     April 1997
  11.  
  12.  
  13.  
  14.     You can freely distribute this library, as long as it is free of
  15.     charge and it contains all the files listed in the file FILES.LST, 
  16.     intact and unmodified. This library may be used for any purpose (even
  17.     included into commercial products), provided that the developer gives
  18.     credit to the original author.
  19.  
  20.     Feel free to suggest enhancements, find bugs and report them to me.
  21.  
  22.     If you use the library, please let me know, so I can find out if this
  23.     library is useful.
  24.  
  25.     DISCLAIMER
  26.  
  27.     All software and documentation associated with the XMSBCP library is
  28.     provided "as is": ie., it is provided without warranty of any kind, not
  29.     even an implied warranty of merchantability or fitness for any purpose.
  30.  
  31.     I will in no way be held liable for any loss of profit or any other
  32.     commercial damage including but not limited to special, incidental,
  33.     consequential or other damages from use of this software.
  34.  
  35.  
  36.   I. Introduction
  37.   ---------------
  38.  
  39.   Why did I write XMSBCP ?
  40.   ========================
  41.  
  42.   This library was born when I had to write a program that required a huge
  43.   amount of memory, more than 1 MB. I decided to use extended memory so I
  44.   looked for an interface to allow me to access XMS from C. I was not very
  45.   satisfied with what I found (some libraries didn't have all the routines
  46.   I needed, or they didn't include their full source, or they were very slow
  47.   or difficult to use). Then I found the Lotus Intel Microsoft XMS
  48.   specification version 3.0 and after I learned how XMS works I was able to
  49.   write my own routines to access XMS. I grouped them in a library. I also
  50.   wrote a Turbo Pascal unit.
  51.  
  52.   What is XMSBCP ?
  53.   ================
  54.  
  55.   XMSBCP provides a natural and easy-to-use interface to XMS for programs
  56.   compiled using Borland C/C++ and Borland Pascal. XMS (eXtended Memory
  57.   Specification) allows DOS programs to utilize additional memory outside
  58.   the conventional 640K imposed by DOS. XMS provides access to
  59.  
  60.     1. Upper Memory Blocks (UMBs) (memory between 640K and 1024K)
  61.     2. High Memory Area (HMA) (memory between 1024K and 1088K)
  62.     3. Extended Memory Blocks (EMBs) (memory above 1088K)
  63.  
  64.   XMSBCP currently implements all the XMS 3.0 API Functions (HMA Management
  65.   Functions, A20 Management Functions, Extended Memory Management Functions
  66.   and Upper Memory Management Functions). The additional C/C++ and Pascal
  67.   library XMSSUPER, that will be included in this package in the next release
  68.   will also implement the Super Extended Memory Support found in XMS 3.0 that
  69.   provides support for extended memory pools up to 4 Gb in size.
  70.  
  71.   XMSBCP is written using the Borland C and Borland Pascal built-in assembler
  72.   for speed and small size.
  73.  
  74.   Full source code (in C/C++ and Pascal) is included.
  75.  
  76.   What is supported ?
  77.   ===================
  78.  
  79.   XMSBCP expressly supports the Microsoft eXtended Memory Specification (XMS)
  80.   versions 2.0 and 3.0. Versions below 2.0 are not supported. Versions above
  81.   3.0 are supported as 3.0. The only function supported only by XMS 3.0 or
  82.   above is umbrealloc/UMBReAlloc.
  83.  
  84.   The C/C++ version of XMSBCP supports all memory models (tiny, small,
  85.   medium, compact, large and huge). Libraries compiled with Borland C/C++ 3.1
  86.   are provided for all memory models. The C/C++ version has been tested with
  87.   Borland C++ 3.1 in both C and C++ modes. If you recompile and test the
  88.   library with other compilers and it works, please let me know.
  89.  
  90.   The Pascal version of XMSBCP supports Turbo and Borland Pascal 7.0.
  91.  
  92.   What's new in version 1.1 ?
  93.   ===========================
  94.  
  95.   The C/C++ version of XMSBCP now supports all memory models (libraries
  96.   compiled with Borland C/C++ 3.1 are provided).
  97.  
  98.   Some changes and improvements were made to the C/C++ version: the memory
  99.   copy routines (ctoxm, xmtoc, xmtoxm, ctoc) are now implemented as macros
  100.   (in C) / inline functions (in C++) to increase speed; the xmsinstalled
  101.   variable was defined to test if an XMS driver is installed without having
  102.   to recall xmsinit; a bug was fixed in MDCOPY (the library test program).
  103.  
  104.   Minor changes and improvements were made to the Pascal version too.
  105.  
  106.   The documentation has been rewritten and improved.
  107.  
  108.  
  109.   II. Compiling and linking with XMSBCP
  110.   -------------------------------------
  111.  
  112.   To use XMSBCP into a C/C++ program, include the header file XMS.H and
  113.   link the program with the library corresponding to the memory model in
  114.   which you have compiled the program.
  115.  
  116.   To use XMSBCP into a Pascal program just add XMS in the uses clause.
  117.  
  118.  
  119.   III. Programming with XMSBCP
  120.   ----------------------------
  121.  
  122.   The library initialization function initxms() (InitXMS in Pascal version)
  123.   must be called before any other XMSBCP routines. All other XMSBCP functions
  124.   will fail if called before the initialization function.
  125.  
  126. > For the C/C++ version
  127.   Initxms() is automatically called when you include xms.h (a "#pragma
  128.   startup initxms" directive is placed in xms.h).
  129.  
  130. > For the Pascal version
  131.   InitXMS is automatically called when you use xms.tpu (XMSInit is called in
  132.   the initialization part of the xms unit).
  133.  
  134.   After calling the initialization function you can
  135.  
  136.   - get the XMS driver version (xmsver/XMSVersion, xmsverinfo/XMSVersionInfo)
  137.  
  138.   - allocate the High Memory Area (HMA) (hmarequest/HMARequest)
  139.   - release the HMA (hmarelease/HMARelease)
  140.  
  141.   - get the amount of free extended memory (xmfreespace/XMFreeSpace)
  142.   - get the size of the largest free extended memory block (xmcontig/XMContig)
  143.   - allocate extended memory blocks (EMBs) (xmalloc/XMAlloc)
  144.   - resize EMBs (xmrealloc/XMRealloc)
  145.   - free EMBs (xmfree/XMFree)
  146.   - lock EMBs (xmlock/XMLock)
  147.   - unlock EMBs (xmunlock/XMUnlock)
  148.  
  149.   - transfer data from conventional to extended memory (ctoxm/CopyCMemToXMem)
  150.   - transfer data from extended to conventional memory (xmtoc/CopyXMemToCMem)
  151.   - transfer data within extended memory (xmtoxm/CopyXMem)
  152.   - transfer data within conventional memory (ctoc/CopyMem)
  153.  
  154.   - allocate upper memory blocks (UMBs) (umballoc/UMBAlloc)
  155.   - resize UMBs (umbrealloc/UMBReAlloc)
  156.   - free UMBs (umbfree/UMBFree)
  157.  
  158.   - return an adequate description of the last XMS error that occured
  159.     (xmserrormsg/XMSErrorMsg)
  160.  
  161.   , etc.
  162.  
  163.   Many functions return 1 on success and 0 on failure (in this case an error
  164.   code is returned in xmserrno (C) or in XMSError (PASCAL) ).
  165.  
  166.   A short description of all XMSBCP constants/types/variables/functions can
  167.   be found in the DESCRIP.TXT file.
  168.  
  169.  
  170.   IV. Release Information
  171.   -----------------------
  172.  
  173.   Version 1.1
  174.  
  175.     + Support for all memory models (C/C++).
  176.     + Included compiled libraries for all memory models (C/C++).
  177.     + Rewritten and improved documentation.
  178.     + Changed name to reflect version information.
  179.     + Miscellaneous changes and improvements (C/C++ and Pascal).
  180.  
  181.   Version 1.0
  182.  
  183.     First official release.
  184.  
  185.  
  186.   V. Plans for future releases
  187.   ----------------------------
  188.  
  189.   + The additional XMSSUPER C/C++ and Pascal library that will implement
  190.     the Super Extended Memory Support found in XMS 3.0.
  191.  
  192.   + An Object-Oriented Interface for Extended Memory Blocks, Upper Memory
  193.     Blocks, High Memory Area, XMS Errors, both in C++ and Pascal.
  194.  
  195.   The more feedback I get the more likely I am to achieve these goals or
  196.   to continue writing programming libraries.
  197.  
  198.   If you are interested in computer programming (as I am), please contact
  199.   me (my favourite subjects are OOP, C/C++, assembler, text user interfaces,
  200.   etc.).
  201.  
  202. ───────────────────────────────────────────────────────────────────────────
  203.  
  204.     Tanescu A. Horatiu (alpha@lego.soroscj.ro)
  205.     "Emanuil Gojdu" High School Oradea Romania
  206.  
  207. ───────────────────────────────────────────────────────────────────────────